home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 3 / Light ROM 3 - Disc 2.iso / programs / amiga / jpeggers / jpeg_aga / jpeg_aga.txt < prev   
Text File  |  1995-03-23  |  18KB  |  495 lines
  1.  
  2.                          jpegAGA 2.1 by Gⁿnther R÷hrich
  3.                          ******************************
  4.  
  5. There are no new features in this release (compared to jpegAGA 2.0), only a
  6. bug has been fixed.
  7.  
  8. jpegAGA is, at this time, the highest quality JPEG viewer (if a map-file for
  9. that picture is available) To use it you need the AGA chipset, a 68020 or
  10. higher processor and OS 3.0 or higher. This program uses the HAM8-mode, gray-
  11. scale display will use 256-color-mode. Although jpegAGA 2.0 has many new
  12. features it is still fully compatible to the previous versions.
  13.  
  14. If a precomputed colormap (a file with the ending .map) is available then
  15. the picture will be displayed in a much higher quality compared to all other
  16. viewers.
  17. With the supplied shell script you can create such map-files for all your
  18. pictures. These files will only be 198 bytes long.
  19.  
  20. If a map-file is not available then you will get a lower quality display. For
  21. grayscale display this file is not needed.
  22.  
  23. The advantages of jpegAGA:
  24. - very high quality (better than any other viewer)
  25. - complete source is available
  26. - best compatibility to all JPEG pictures because the unmodified JPEG source
  27.   from the Independent JPEG group is used for decoding
  28.   (jpegAGA 2.0 uses version 5A)
  29. - high speed gained by using the GNU C compiler and the 24-bit-RGB to HAM8 con-
  30.   verter written directly in assembly language
  31. - support for grayscale JPEG's and for showing color pictures in grayscale
  32.   format
  33. - automatic screen mode selection, depending on the size of the picture
  34. - pictures can be shown at reduced size, useful for high speed previews
  35. - they can be scaled automatically to fit completely on your screen
  36. - when more than one picture is selected jpegAGA will load and decode the next
  37.   picture in the background while you are still looking at the previous one
  38.  
  39.  
  40. This program and the supplied source is Public Domain, you can do what you want
  41. with it. For the IJG JPEG sources please read the file README.
  42.  
  43.  
  44. I have to thank the following persons/groups:
  45.  
  46. My betatesters:
  47.  Denis Ahrens (d.ahrens@bamp.berlinet.in-berlin.de)
  48.  Lars Tewes (LSR@quick.sh.sub.de)
  49.  Tim Reddy (tcreddy@prairienet.org)
  50. and all the others not mentioned here.
  51.  
  52. The Independent JPEG Group (jpeg-info@uunet.uu.net):
  53.  for the source to decode/encode the JPEG picture format
  54.  
  55. Free Software Foundation, Inc. and all contributors for the GNU C compiler
  56. and related tools
  57.  
  58. Martin Huttenloher (xen@magic.in-ulm.de)
  59.  for the wonderful MagicWB icons
  60.  
  61. ***********************************************************************
  62.  
  63.  
  64. Now let's go on with the real documentation:
  65.  
  66.  
  67. Installation
  68. ************
  69.  
  70. Copy the programs from the bin directory anywhere into your shell's search
  71. path. The file name extensions are showing for what processors they are com-
  72. piled. After installation you should remove these extensions. Workbench users
  73. can place the main program (jpegAGA.020) anywhere they want.
  74.  
  75. Extension 000:  68000 and 68010 processors, runs on all others too
  76. Extension 020:  only for 68020 or higher processors
  77. Extension 020881: only for 68020 or higher processors with a coprocessor
  78.  
  79. All programs are compiled with the gcc compiler. The programs djpeg, cjpeg and
  80. ppm2AGA  will need the ixemul.library (version 39 or higher) in the LIBS:
  81. directory. jpegAGA itself does not need this library.
  82.  
  83. For using the shell scripts CreateMap(Big) you have to assign JPEGTMP: to a
  84. directory on your hard disk with enough free space. (e.g. assign JPEGTMP: HD:T)
  85. The programs djpeg and cjpeg will eventually need this directory too.
  86. The best solution is to add this command to the user-startup file.
  87.  
  88. The shell scripts CreateMap and CreateMapBig should be copied to the S:
  89. directory. They assume that the programs djpeg and ppm2AGA are available (with
  90. exactly these names) in the shell's search path and the JPEGTMP: directory
  91. exists.
  92.  
  93.  
  94.  
  95. Invoking jpegAGA:
  96.  
  97. from the Shell:
  98.  
  99.   jpegAGA options inputfiles
  100.  
  101. from the Workbench:
  102.  
  103.  Double click on the program icon or on a project icon of your pictures. Of
  104. course, you have to prepare the project icons first.
  105.  
  106. Shell-users can use the script PV for fast previews. It is used similar as
  107. jpegAGA itself but lot of options are predefined. This saves you a lot of
  108. work at typing in the shell.
  109.  
  110.  
  111. Inputfiles
  112. **********
  113.  
  114. The name of the JPEG-file that should be read. You can specify as many files as
  115. you want, at any place in the command line. Wildcards (e.g. #?.jpg) are also
  116. supported. If you want to use a file name that starts with "-" you must use "?"
  117. instead. (Otherwise jpegAGA will assume that you used a wrong option.) If you
  118. have not specified any file names a file requester will be displayed. You can
  119. select multiple pictures with the Shift-key. Remove the default pattern if you
  120. want to select file names that do not end with ".jpg" or ".jpeg".
  121.  
  122. If you started the program with a double click from Workbench you will also get
  123. the file requester if you have not selected any pictures. (by using the Shift
  124. key) It is much more comfortable when you create a project icon for each of your
  125. pictures. As the default tool enter jpegAGA, including the complete path. Now
  126. you can look at the picture simply by double clicking on it. You can select
  127. multiple pictures with the extended selection feature of the Workbench. This is
  128. recommended because jpegAGA will then use background loading and economize time.
  129.  
  130. All input files must be JPEG pictures in the JFIF format, either 24 Bit RGB or
  131. grayscale.
  132. Grayscale pictures will be shown on a 256 colors screen without extensive
  133. computations. Unfortunately there are also grayscale pictures encoded in color
  134. mode. You should use the -GRAY option for such pictures.
  135.  
  136. When showing the picture in color mode the map-file for this picture will be
  137. used if it is available. The map-file must have the same name as the picture
  138. with the additional ending .map. To support the PC-filesystem it will also
  139. accept a name that has the extension replaced by ".map".
  140. If a map-file is found this will be notified in the console window.
  141.  
  142. Examples for file names:
  143.  
  144. picture file: picture.jpeg    map-file: picture.jpeg.map  or  picture.map
  145.               pic1.jpg        map-file: pic1.jpg.map      or  pic1.map
  146.  
  147. jpegAGA will also try to find the map-file in the directory pointed to by
  148. the environment variable MAPDIR.
  149.  
  150.  
  151. Options
  152. *******
  153.  
  154. Options can be used anywhere in the command line, they are case-insensitive.
  155. If they are not set then internal default values will be used.
  156.  
  157. Workbench users can set options with the "ARGS" tool type.
  158. (e.g. ARGS= -vga -scale 1/2 -gray)
  159. If the picture has a icon then the tool types of this icon will also be taken
  160. into account. These option will override those from the jpegAGA program icon,
  161. but they are individual, only for a single picture. If you selected the picture
  162. with the file requester the tool types of the pictures will not be processed.
  163. This is also the case for Shell invocation.
  164.  
  165.  
  166. -GRAY
  167.  
  168. Display picture in grayscale mode. This is much faster than color display and
  169. is therefore useful for a fast preview.
  170.  
  171.  
  172. -VGA
  173.  
  174. The picture will always use the VGA screenmode (also called 'multiscan') for
  175. display. Use this option when you know that the picture was intended for
  176. displaying on a PC or other machines with square  screen resolution.
  177. (this is the case for most JPEG-pictures)
  178.  
  179. NOTE: With 'square' I don't mean that the screen has the same number of pixels
  180. in horizontal and vertical direction. (e.g. 1024x1024)
  181. I mean that a square composed of e.g. 100x100 pixels will be shown as a
  182. square on the screen. Because a usual picture tube has a ratio of 4 to 3
  183. the screen's resolution must be a multiple of that. (e.g. 640x480 because
  184.  
  185.  640   4
  186.  --- = - )
  187.  480   3
  188.  
  189.  
  190. -SUPER72
  191.  
  192. This option will only be accepted if you also set the -VGA  option. The SUPER72
  193. screen mode will be used for very large pictures. You have to modify the SUPER72
  194. monitor driver in most of the cases (e.g. with the program "moned") if you want
  195. to get a square resolution in that mode.
  196.  
  197.  
  198. -SCALE 1/x (new in version 2.0)
  199.  
  200. The picture will be scaled by a factor of 1/x. Supported are 1/1, 1/2, 1/4 and
  201. 1/8. Pictures at reduced size will be shown much faster, you can use this
  202. option for a fast preview.
  203.  
  204.  
  205. -FIT (new in version 2.0)
  206.  
  207. The picture will be scaled to fit completely on the screen. A tolerance of about
  208. 35 pixels is allowed. Scaling is possible only with the factors 1/2, 1/4 and
  209. 1/8. The options -VGA and -SUPER72 will also be taken into account. The SUPER72
  210. mode will only be used if the picture is too big for a VGA screen.
  211.  
  212.  
  213. -NOSMOOTH (new in version 2.0)
  214.  
  215. -DCT FAST (new in version 2.0)
  216.  
  217. With these options decoding is a bit faster but the picture quality gets worse.
  218. You can use these options for fast previews.
  219.  
  220.  
  221. -SMR (new in version 2.0)
  222.  
  223. When this option is set you can choose the screen mode with a requester. Back-
  224. ground loading does not work any more because you must choose a screen mode
  225. before a picture is shown. This option is ignored if it is set as a tool type
  226. of a picture icon.
  227.  
  228.  
  229. For picture icons there are additional options available. You can use them to
  230. disable options that are set in the jpegAGA icon. For example, if you use the
  231. option -NOGRAY in the picture icon then the picture will be shown colored, even
  232. if the -GRAY option is set in the jpegAGA icon.
  233.  
  234. option         counterpart (picture icon only)
  235.  
  236. -DCT FAST      -DCT INT
  237. -NOSMOOTH      -SMOOTH
  238. -GRAY          -NOGRAY
  239. -VGA           -NOVGA
  240. -SUPER72       -NOSUPER72
  241. -FIT           -NOFIT
  242.  
  243.  
  244. If you started jpegAGA with a wrong option (e.g. -v) you will get a list of all
  245. available options, including a short description. This works from Shell only.
  246.  
  247. There is also a JPEG decompression program included. It converts JPEG pictures
  248. to the ppm format. (It is also needed for creating the map-files.)
  249. To use it enter:
  250.  
  251.  djpeg inputfile outputfile
  252.  
  253. In some cases djpeg will try to store temporary files to JPEGTMP:, you
  254. have then to assign this directory to somewhere on your hard disk.
  255. (for example assign JPEGTMP: HD:T)
  256. For more informations read the included documentation.
  257. With the program cjpeg you can create your own JPEG files.
  258.  
  259.  
  260.  
  261. Creating the map-files
  262. **********************
  263.  
  264. These files are needed for showing color picture with best possible quality.
  265. Normally, they are created by the shell-script CreateMap.
  266. Usage: (from Shell)
  267.  
  268.  CreateMap picturefile
  269.  
  270. After succesfull completion a map-file with the correct name will be created.
  271. (On PC-filesystems too) You can process several pictures with a single invo-
  272. cation. The command
  273.  
  274.  SPat CreateMap pictures/#?.jpg
  275.  
  276. will create, for example, a map-file for all pictures with the extension .jpg
  277. in the directory pictures.
  278. If it is not possible to store the map-file at the same location as the picture
  279. itself then it will be stored in the directory pointed to by the environment
  280. variable MAPDIR. You can set the environment variable e.g. with the command:
  281.  
  282.  setenv MAPDIR HD:tempdir
  283.  
  284. If you reset your machine the variable will get lost. To prevent this you can
  285. use the command:
  286.  
  287.  copy ENV:MAPDIR ENVARC:
  288.  
  289. Now you can also show pictures from a CD-ROM with best possible quality.
  290.  
  291. NOTE: You must take care that the same map-file will not be used for different
  292. pictures. Otherwise you will get lower picture quality.
  293.  
  294. With the shell-script "CreateMapBig" mapfile creation is much faster. While
  295. decoding the picture it will be scaled down by 1/2. This does no harm (at
  296. least for large pictures) because only the color distribution is of interest
  297. and not the whole picture. For very big pictures you may even scale by 1/4, you
  298. will have to edit the script a bit.
  299. For small pictures (e.g. 320x200 pixels) you should not reduce the size and
  300. use the normal "CreateMap" script. It is also recommended for use if you are
  301. processing a complete directory with both big and small pictures.
  302.  
  303.  
  304. If problems occur please check the following:
  305.  
  306. - Have you installed everything as it is described in the section
  307.   "Installation" ?
  308.  
  309.   The files djpeg and ppm2AGA are needed under these names in the search path.
  310.   ixemul.library must exist in the LIBS: directory an the shell-script itself
  311.   must be in the S: directory.
  312.  
  313.   attention: - ppm2AGA must have version 1.4 or higher
  314.              - use djpeg from this distribution only
  315.  
  316.  
  317. - Have you assigned the directory JPEGTMP: correctly ?
  318.  
  319.  
  320. - Has the hard disk partion enough free space ?
  321.  
  322.   When using the CreateMapBig script less disk space will be needed.
  323.  
  324. - Is enough memory available ?
  325.  
  326.   If not you can reduce memory usage by using the -M0 option with the shell
  327.   script. (See the documentation for ppm2AGA for more.)
  328.  
  329.   example: CreateMap pic.jpg -M0 or SPat CreateMap #?.jpg -M0
  330.  
  331.  
  332. - Is the disk, on which the JPEG-picture is stored, write enabled and does it
  333.   has enough free space ?
  334.  
  335. - Have you set the environment variable MAPDIR correctly ? You can check this
  336.   with the command: getenv MAPDIR
  337.  
  338. You can interrupt the shell-script at any time by pressing CTRL-C. In this case
  339. all temporary files in the directory JPEGTMP: will be removed automatically.
  340.  
  341.  
  342.  
  343. The picture screen
  344. ******************
  345.  
  346. You can move it around with the mouse. It also has an invisible, but full
  347. functional drag bar and depth gadget. In color mode you will see errors at the
  348. left side, they are caused by the HAM encoding. In this version they are 
  349. usually smaller than with other programs.
  350. Pressing the right mouse button will close the screen or switch to the next
  351. one. If there is not enough Chip RAM to open the next screen in the background
  352. jpegAGA will wait till the previous screen will get closed and will try it
  353. again. If the mouse pointer remains in the busy state after a picture is
  354. completely finished then you will know that the next one is loaded in the back-
  355. ground.
  356. Pressing the left mouse button has no effect. This means that you can activate
  357. another screen at any time and re-activate the picture screen again.
  358. Pressing the Esc key will completely finish the program. This is useful if you
  359. selected multiple pictures.
  360.  
  361. NOTE: Because of some bugs in the OS it can happen that pictures are shown
  362. cropped or even totally corrupted. In this case you should move the picture
  363. to the right till it is shown correctly.
  364.  
  365.  
  366. If you have additional questions, suggestions for enhancements, bug reports,
  367. Mungwall/Enforcer hits, etc. then please contact me. It would also be nice
  368. if you would send me a corrected version of this manual. (and for ppm2AGA too)
  369.  
  370.  
  371. Here is where you can get all the other programs and libraries that are included
  372. in the jpegAGA archive. If you can find new versions in other places you should
  373. use them, don't wait till they will appear in the jpegAGA archive!
  374.  
  375.  
  376. Actual situation: (14-Jan-1995)
  377.  
  378. ixemul.library
  379. **************
  380.  
  381. Included in the jpegAGA 2.0 archive: version 40.4, 68000, noFPU
  382.  
  383. Latest version: 40.4
  384.  
  385. Archive location (on Aminet): dev/gcc/ixem*lib.lha
  386.  
  387.  
  388. djpeg, cjpeg
  389. ************
  390.  
  391. Included in the jpegAGA 2.0 archive: V5a
  392.  
  393. Latest version: V5a
  394.  
  395. Archive location (on Aminet): gfx/conv/jpegV*bin.lha
  396.                               gfx/conv/jpegV*src.lha
  397.  
  398.  
  399. History
  400. *******
  401.  
  402. 1.0 - 4-June-1994
  403.  
  404.     - first public release
  405.  
  406. 1.1 - 5-October-1994
  407.  
  408.     - added the option -SUPER72
  409.  
  410.     - the picture screen no longer flashes when closing it and the delay is much
  411.       smaller now
  412.  
  413.     - map-files will also be searched in the directory pointed to by the MAPDIR
  414.       environment variable
  415.  
  416.     - if a map-file is not found the user will get informed that he/she should
  417.       create one
  418.  
  419.     - file/path names of any length are now accepted
  420.  
  421. 2.0 - 14-January-1995
  422.  
  423.     - slightly faster
  424.  
  425.     - the ixemul.library is not needed any more
  426.  
  427.     - version 5A of the JPEG source from the Independent JPEG Group is used
  428.       (instead of V4 in jpegAGA 1.x)
  429.  
  430.     - input buffer size is now 32768 bytes, normal dos.library calls will be
  431.       used for all file operations
  432.  
  433.     - added the options -SCALE, -FIT, -NOSMOOTH, -DCT FAST and -SMR
  434.  
  435.     - added the background loading feature
  436.  
  437.     - pressing the Esc button will completely stop the program, pressing the
  438.       right mouse button switches to the next picture
  439.  
  440.     - the picture screen opens with the correct colors, no flashing after
  441.       opening
  442.  
  443.     - multiple files and wildcards are supported, at any place in the command
  444.       line
  445.  
  446.     - selecting the pictures with a file requester is possible
  447.  
  448.     - full Workbench support, but there is still no GUI
  449.  
  450.     - messages in the console window are much better
  451.  
  452.     - there is now a makefile for the Aztec compiler supplied with the source
  453.       
  454.     - enhanced the HAM8 encoder, if you move the picture screen around the
  455.       errors on the left side will be much smaller
  456.  
  457. 2.1 - 4-February-1995
  458.  
  459.     - bug fixed: when the window or the temporary bitmap could not be opened on
  460.       a screen the program will operate now correctly
  461.  
  462.  
  463. Announcement
  464. ************
  465.  
  466. My spare time is very limited because I am now studying Electrical Engineering
  467. at the University Stuttgart. Therefore I am searching for other developers to
  468. cooperate with me and beta-testers for testing purposes. I am especially sear-
  469. ching for someone to write a GUI.
  470. If you want to join in then please contact me. I will then create a detailed
  471. description of the source. You can use any C development system available for
  472. the Amiga but only the gcc compiler will create the best possible optimization.
  473.  
  474. To recompile ppm2AGA you need the newiff package from Commodore.
  475. V37 is available on Fish-disk 705, V39 on the "3.1 Amiga Developer Update"
  476. disks and on Aminet. 
  477.  
  478.  
  479. To contact me write to:
  480.  
  481.   electronic mail:                                  normal mail:
  482.   ****************                                  ************
  483.  
  484.  Guenther@studbox.uni-stuttgart.de                  Gⁿnther R÷hrich
  485.      (Internet EMAIL)                               Lerchenbergstr. 4
  486.                                                     73733 Esslingen
  487.                                                         Germany
  488.  
  489.  
  490. If you don't get an answer to a EMAIL within 3 weeks then try it again
  491. with normal mail.
  492.  
  493. For compiling the programs you will need the OS 3.x includes. They are available
  494. in the "3.1 Amiga Developer Update" or on the Fresh Fish CD-ROM's.
  495.